MODULE = PlPN          PACKAGE = PlPN::Recorder

#
# this package doesn't used the standard XS/C++ interface
# because the object is a boost shared_ptr, not a real pointer
#

#
# Pod::Html is kind of brain-dead:
#
# Place Z<> between function names and parentheses, otherwise Pod::Html
# assumes you meant to put C<...> around it
#
# Put explicit text in all links L<use my text, stupid|some::perl::module>,
# otherwise Pod::Html assumes you want "the X manpage". (Does not apply to
# relative links withing this file.)
#
# It also assumes you want a link if you have C<...> with text matching a
# potential link target. The only way I've found around that is to split it
# up into multiple pieces: C<wo>C<rd>. Looks correct in the resulting HTML,
# but it's ugly to have <code>wo</code><code>rd</code> in the source, and I
# shouldn't have to do it.
#

=head1 NAME

PlPN::Recorder - The macro recorder object

=head1 SYNOPSIS

	{
		package MyRecorderWithUniqueClassName;
		use PlPN;
		our @ISA = qw(PlPN::Recorder);
		
		sub new {
			my $class = shift;
			my $self = $class->SUPER::new(@_);
			# do something with $self
			return $self;
		}
		
		sub RecordScintillaAction {
			# do something
		}
		
		# etc.
	} # scope ends; return to original package
	
	use PlPN qw(PN);
	
	my $recorder = new MyRecorderWithUniqueClassName;
	PN->AddRecorder($recorder);
	
	# etc.

=head1 DESCRIPTION

Catches macro recording events from Programmer's Notepad.

The default constructor simply blesses an empty hashref into the class.

The default events do nothing; they exist so that derived classes can omit
them without causing Perl to crash when C++ code tries to call the event.

If you write a recorder, it is up to you to determine a format to store
actions in.

L<PlPN|PlPN> currently implements no default recorder, so if you want to
record and play back macros, you need to write your own.

=head1 EVENTS

=over

=cut

SV*
new(CLASS)
		const char* CLASS;
	CODE:
		HV* hv = newHV();
		RETVAL = newRV_noinc((SV*)hv);
		sv_bless(
			RETVAL,					/* reference to be blessed */
			gv_stashpv(CLASS, 1)	/* stash to bless it into */
		);
	OUTPUT:
		RETVAL

void
DESTROY(THIS)
		SV* THIS;
	CODE:
		g_recorder->DetachPerlSink(THIS);

=item RecordScintillaActionZ<>($message, $wParam, $lParam)

The default event called when a Scintilla action occurs; called only if
there isn't a more specific event. (Since there is only one other event,
this one gets called for most actions.)

See L<PlPN::Document::SendEditorMessage|PlPN::Document/SendEditorMessage>.

Please note that in the current implementation all parameters are passed as
integers. Later versions will probably make necessary string conversions in
the XS code. For now, it is up to you to determine (based on the C<$message>
whether a parameter is a string pointer and if it is, you must unpack the
pointer yourself.

=cut

void
RecordScintillaAction(...)
	CODE:
		// default implementation so we don't croak for lack of a method

=item RecordSearchActionZ<>($type, $options, $result);

This event is called for search actions. C<$type> is one of the search type
indicators exposed via the C<:SearchType> tag in L<PlPN|PlPN>. These
constants are:

=over

=item stFindNext

=item stReplace

=item stReplaceAll

=back

C<$options> is a L<PlPN::SearchOptions|PlPN::SearchOptions> object.
C<$result> is a C<FindNextResult> indicator. (See
L<PlPN::Document::FindNext|PlPN::Document/FindNext>.)

=cut

void
RecordSearchAction(...)
	CODE:
		// default implementation so we don't croak for lack of a method

=item StartRecordingZ<>();

This event is called when the user selects C<Record Script> from the
Programmer's Notepad C<Tools> menu. It is your signal to do any preparatory
work to get ready to record a macro.

=cut

void
StartRecording(...)
	CODE:
		// default implementation so we don't croak for lack of a method

=item StopRecordingZ<>();

This event is called when the user selects C<Stop Recording> from the
Programmer's Notepad C<Tools> menu. This is where you should format and
store your macro.

=cut

void
StopRecording(...)
	CODE:
		// default implementation so we don't croak for lack of a method

=back

=head1 COPYRIGHT and LICENCE

Copyright (c) 2012 Sean Healy. All rights reserved.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.

=cut
